Microsoft CodeView and Utilities
================================
CHAPTER 5 ___ EXECUTING CODE

Several commands execute code within a program.  Among the differences between
the commands is the size of step executed by each.  The commands and their
step sizes are listed below.

Command		Action
------------------------------
Trace (T)	Executes the current source line in source mode, or the
		current instruction in assembly mode;  traces into
		routines, procedures, or interrupts

Program Step (P)	Executes the current source line in source mode, or the
		current instruction in assembly mode;  steps over routines,
		procedures, or interrupts

Go (G)		Executes the current program

Execute (E)	Executes the current program in slow motion

Restart (L)	Restarts the current program.

In window mode, the screen is updated to reflect changes that occur when you
execute a Trace, Program Step, or Go command.  The highlight marking the
current location is moved to the new instruction in the display window.  When
appropriate, values are changed in the register and watch windows.

In sequential mode, the current source line or instruction is displayed after
each Trace, Program Step, or Go command.  The format of the display depends on
the display mode.  The three display modes available in sequential mode
(source, assembly, and mixed) are discussed in Chapter 9, "Examining Code."

If the display mode is source (S+) in sequential mode, the current source line
is shown.  If the display mode is assembly (S-), the status of the registers
and the flags and the new instruction are shown in the format of the Register
command (see Chapter 6, "Examining Data and Expressions").  If the display
mode is mixed (S&), then the registers, the new source line, and the new
instruction are all shown.

The commands that execute code are explained in Sections 5.1--5,5,
----
Note
----
If you are executing a section of code with the Go or Program Step command,
you can usually interrupt program execution by pressing CONTROL+BREAK or
CONTROL+C.  This can terminate endless loops, or it can interrupt loops
that are delayed by the Watchpoint or Tracepoint command (see Chapter 8,
"Managing Watch Statements").  CONTROL+BREAK or CONTROL+C may not work if
your program has a special use for either of these key combinations.  If
you have an IBM Personal Computer AT (or a compatible computer), you can
use the SYSTEM-REQUEST key to interrupt execution regardless of your
program's use of CONTROL+BREAK and CONTROL+C.
====

5.1  Trace Command

The Trace command executes the current source line in source mode, or the
current instruction in assembly mode.  The current source line or instruction
is the one pointed to by the CS and IP registers.  In window mode, the current
instruction is shown in reverse video or in a contrasting color.

In source mode, if the current source line contains a call, the CodeView
debugger executes the first source line of the called routine.  In this mode,
the CodeView debugger will only trace into functions and routines that have
source code.  For example, if the current line contains a call to an intrinsic
function or a standard C library function, the debugger will simply execute
the function if you are in source mode, since the source code for Microsoft
standard libraries is not available.

If you are in assembly or mixed mode, the debugger will trace into the 
function.  In this mode, if the current instruction is CALL, INT, or REP, the
debugger executes the first instruction of the procedure, interrupt, or
repeated string sequence.

----
Note
----
When you debug Microsoft Macro Assembler programs in source mode, the
paragraph above still applies.  The debugger will not trace into an INT
or REP sequence when you are in source mode.
====

Use the Trace command if you want to trace into calls.  To execute calls
without tracing into them, you should use the Program Step command (P)
instead.  Both commands execute DOS function calls without tracing into them.
There is no direct way to trace into DOS function calls.  However, you can
trace through BIOS calls in assembly or mixed mode.

----
Note
----
The Trace command (T) uses the hardware trace mode of the 8086 family of
processors.  Consequently, you can also trace instructions stored in ROM
(read-only memory).  However, the Program Step command (P) will not work in
ROM.  Using the Program Step command has the same effect as using the Go
command (G).
====

<*> Mouse

To execute the Trace command with the mouse, point to Trace on the menu bar
and click the left button.

<*> Keyboard

To execute the Trace command with a keyboard command, press the F8 key.  This
works in both window and sequential modes.

<*> Dialog

To execute the Trace command using a dialog command, enter a command line with
the following syntax:

T [count]

If the optional count is specified, the command executes count times before
stopping.

<*> Example

The following example shows the Trace command in sequential mode. (In window
mode, there would be no output from the commands, but the display would be
updated to show changes caused by the command.)

>S+	;* FORTRAN example
source
>.
9:		CALL INPUT (DATA,N,INPFMT)
>T 3
34:		OPEN (1,FILE='EXAMPLE.DAT',STATUS='OLD')
35:		DO 100 I=1,N
36:		READ (1,'(BN,I10)',END=999) DATA(I)

>

The FORTRAN example above sets the display mode to source, and then uses the
Source Line command to display the current source line. (See Chapter 9,
"Examining Code," for a further explanation of the Set Source and Source Line
commands.) Note that the current source line calls the subroutine INPUT.  The
Trace command is then used to execute the next three source lines.  These
lines will be the first three lines of the subroutine INPUT.

Debugging C and BASIC source code is very similar.  If you execute the Trace
command when the current source line contains a C function call or a BASIC
subprogram call, then the debugger will execute the first line of the called
routine.

>S-
assembly
>T
AX=0058  BX=3050  CX=000B  DX=3FB0  SP=304C  BP=3056  SI=00CC  DI=40E0
DS=49B7  ES=49B7  SS=49B7  CS=3FB0  IP=0013  NV UP EI PL NZ AC PO NC
3FB0:0013 50             PUSH      AX
>

The example above sets the display mode to assembly and traces the current
instruction.  This example and the next example are the same as the examples
of the Program Step command in Section 5.2.  The Trace and Program Step
commands behave differently only when the current instruction is a CALL, INT,
or REP instruction.

>S&
mixed
>T
AX=0000  BX=319C  CX=0028  DX=0000  SP=304C  BP=3056  SI=00CC  DI=40E0
DS=49B7  ES=49B7  SS=49B7  CS=3FB0  IP=003C  NV UP EI PL NZ NA PO NC
8:                IF  (N.LT.1 .OR. N.GT.1000) GO TO 100
3FB0:003C 833ECE2101    CMP     Word Ptr [21CE],+01       DS:21CE=0028
>

The example above sets the display mode to mixed and traces the current
instruction.

5.2  Program Step Command

The Program Step command executes the current source line in source mode, or
the current instruction in assembly mode.  The current source line or
instruction is the one pointed to by the CS and IP registers.  In window mode,
the current instruction is shown in reverse video or in a contrasting color.

In source mode, if the current source line contains a call, the CodeView
debugger executes the entire routine and is ready to execute the line after
the call.  In assembly mode, if the current instruction is CALL, INT, or REP,
the debugger executes the entire procedure, interrupt, or repeated string
sequence.

Use the Program Step command if you want to execute over routine, function,
procedure, and interrupt calls.  If you want to trace into calls, you should
use the Trace command (T) instead.  Both commands execute DOS function calls
without tracing into them.  There is no direct way to trace into DOS function
calls.

<*> Mouse

To execute the Program Step command with the mouse, point to Trace on the menu
bar and click the right button.

<*> Keyboard

To execute the Program Step command with a keyboard command, press the F10
key.  This works in both window and sequential modes.

<*> Dialog

To execute the Program Step command with a dialog command, enter a command
line with the following syntax:

P [count]

If the optional count is specified, the command exectues count times before
stopping.

<*> Example

This example shows the Program Step command in sequential mode.  In window
mode, there would be no output from the commands, but the display would be
updated to show changes.

>S+       ;* FORTRAN/BASIC example
source
>.
9:		CALL INPUT (DATA,N,INPFMT)
>p 3
10:		CALL BUBBLE (DATA,N)
11:		CALL STATS (DATA,N)
12:		END
>

The example above (in FORTRAN or BASIC) sets the display mode to source, and
then uses the Source Line command to display the current source line. (See
Chapter 9, "Examining Code," for a further explanation of the Set Source and
Source Line commands.) Notice that the current source line calls the subpro-
gram INPUT.  The next two steps execute the subprograms BUBBLE and STATS, also
in their entirety.

The same proggram, written in C, would behave exactly the same way with the
Program Step command.  The Program Step command will not trace into a C
function call.

>S-
assembly
>P
AX=0058  BX=3050  CX=000B  DX=3FB0  SP=304C  BP=3056  SI=00CC  DI=40E0
DS=49B7  ES=49B7  SS=49B7  CS=3FB0  IP=0013  NV UP EI PL NZ AC PO NC
3FB0:0013 50             PUSH      AX
>

The example above sets the display mode to assembly and steps through the
current instruction.  This example and the next example are the same as the
examples of the Trace command in Section 5.1.  The Trace and Program Step
commands behave differently only when the current instruction is a CALL, INT,
or REP instruction.

>S&
mixed
>P
AX=0000  BX=139C  CX=0028  DX=0000  SP=304C  BP=3056  SI=00CC  DI=40E0
DS=49B7  ES=49B7  SS=49B7  CS=3FB0  IP=003C  NV UP EI PL NZ NA PO NC
8:                IF (N.LT.1 .OR. N.GT.1000) GO TO 100
3FB0:003C 833ECE2101   CMP     Word Ptr [21CE],+01         DS:21CE=0028
>

The example above sets the display mode to mixed and steps through the current
instruction.

5.3  Go Command

The Go command starts execution at the current address.  There are two
variations of the Go command, Go and Goto.  The Go variation simmmply starts
execution and continues to the end of the program or until a breakpoint set
earlier with the Breakpoint Set (BP), Watchpoint (WP), or Tracepoint (TP)
command is encountered.  The other variation is a Goto command, in which a
destination is given with the command.

If a destination address is given but never encountered (for example, if the
destination is on a program branch that is never taken), the CodeView debugger
executes to the end of the program.

If you enter the Go command and the debugger does not encounter a breakpoint,
the entire program is executed and the following message is displayed:

Program terminated normally (number)

The number in parentheses is the value returned by the program (sometimes
called the exit or "errorlevel" code).

<*> Mouse

To execute the Go command with no destination, point to Go on the menu bar and
press either button.

To execute the Goto variation of the Go command, point to the source line or
instruction you wish to go to; then press the right button.  The highlight
marking the current location will move to the source line or instruction you
pointed to (unless a breakpoint is encountered first).  The CodeView debugger
will sound a warning and take no action if you try to go to a comment line or
other source line that does not correspond to code.

If the line you wish to go to is in another module, you can use the Load
command from the Files menu to load the source file for the other module.
Then point to the destination line and press the right button.

<*> Keyboard

To use a keyboard command to execute the Go command with no destination, press
the F5 key.j  This works in both window and sequential modes.

To execute the Goto variation of the Go command, move the cursor to the source
line or instruction you wish to go to.  If the cursor is in the dialog window,
first press the F6 key to move the cursor to the display window.  When the
cursor is at the appropriate line in the display window, press the F7 key. 
The highlight marking the current location will move to the source line or
instruction you pointed to (unless a breakpoint is encountered first).  The
CodeView debugger will sound a warning and take no action if you try to go to
a comment line or other source line that does not correspond to code.

If the line you wish to go to is in another module, you can use the Load
command from the Files menu to load the source for the other module.  Then
move the cursor to the destination line and press the F7 key.

<*> Dialog

To execute the Go command with a dialog command, enter a command line with the
following syntax:

G [breakaddress]

If the command is given with no argument, execution continues until a
breakpoint or the end of the program is encountered.

The Goto form of the command can be given by specifying breakaddress.  The
breakaddress can be given as a symbol, a line number, or an address in the
segment:offset format.  If the offset address is given without a segment, the
address in the CS register is used as the default segment.  If you give break-
address as a line number, but the corresponding source line isj a comment,
declaration, or blank line, the following message appears:

No code at this line number

<*> Examples

The following examples show the Go command in sequential mode.  In window mode
there would be no output from the commands, but the display would be updated
to show changes caused by the command.

>G

Program terminated normally (O)
>

The example above passes control to the instruction pointed to by the current
values of the CS and IP registers.  No breakpoint is encountered, so the
CodeView debugger executes to the end of the program, where it prints a
termination message and the exit code returned by the program (O in the
example).

>S+       ;* FORTRAN/BASIC example (source mode)
source
>G BUBBLE
17:		A = B + C
>

In the example above, the display mode is first set to source (S+). (See
Chapter 9, "Examining Code," for information on setting the  display mode.)
When the Go command is entered, the CodeView debugger starts program execution
at the current address and continues until it reaches the start of the
subprogram BUBBLE.

>S&	;* C example (mixed mode)
mixed
>G
AX=02F4  BX=0002  CX=00A8  DX=0000  SP=3036  BP=3042  SI=0070  DI=1344
DS=5DAF  ES=5DAF  SS=5DAF  CS=58BB  IP=02A8  NV UP EI PL NZ NA PE NC
58BB:02A8 98             CBW
>

The example above executes to the hexadecimal address CS:2A8.  Since no
segment address is given, the CS register is assumed.

5.4  Execute Command

The Execute command is similar to the Go command with no arguments, except
that it executes in slow motion (several source lines per second).  Execution
starts at the current address and continues to the end of the program or until
a breakpoint, tracepoint, or watchpoint is reached.  You can also stop
automatic program execution by pressing any key or a mouse button.

<*> Mouse

To execute code in slow motion with the mouse, point to Run on the menu bar,
press a mouse button and drag the highlight down to the Execute selection, and
then release the button.

<*> Keyboard

To execute code in slow motion with a keyboard command, press ALT+R to open
the Run menu, and then press ALT+E to select Execute.

<*> Dialog

To execute code in slow motion with a dialog command, enter a command line
with the following syntax:

E

You cannot set a destination for the Execute command as you can for the Go
command.

In sequential mode, the output from the Execute command depends on the display
mode (source, assembly, or mixed).  In assembly or mixed mode, the command
executes one instruction at a time.  The command displays the current status
of the registers and the instruction.  In mixed mode, it will also show a
source line if there is one at the instruction.  In source mode, the command
executes one source line at a time, displaying the lines as it executes them.
---------
Important
---------
The Execute command has the same command letter (E) as the Enter command.
If the command has at least one argument, it is interpreted as Enter; if
not, it is interpreted as Execute.
=========

5.5  Restart Command

The Restart command restarts the current program.  The program is ready to be
executed just as if you had restarted the CodeView debugger. Program variables
are reinitialized, but any existing breakpoints or watch statements are
retained.  The pass count for all breakpoints is reset to 1.  Any program
arguments are also retained, though they can be changed with the dialog
version of the command.

The Restart command can only be used to restart the current program.  If you
wish to load a new program, you must exit and restart the CodeView debugger
with the new program name.

<*> Mouse

To restart the program with the mouse, point to Run on the menu bar, press a
mouse button and drag the highlight down to the Restart or Start selection,
and then release the button.  The program will be restarted.  If the Restart
selection is chosen, the program will be ready to start executing from the
beginning (but not actually running).  If the Start selection is chosen, the
program starts executing from the beginning and continues until a breakpoint
or the end of the program is encountered.

<*> Keyboard

To restart the program with a keyboard command, press ALT+R to open the Run
menu, and then press either ALT+R to select Restart or ALT+S to select Start.
The program will be restarted.  If the Restart selection is chosen, the
program will be ready to start executing from the beginning (but not actually
running).  If the Start selection is chosen, the program starts executing from
the beginning and continues until a breakpoint or the end of the program is
encountered.

<*> Dialog

To restart the program with a dialog command, enter a command line with the
following syntax:

L [arguments]

When you restart using the dialog version of the command, the program will be
ready to start executing from the beginning.  If you want to  restart with new
program arguments, you can give optional arguments.  You cannot specify new
arguments with the mouse or keyboard version of the command.
----
Note
----
The command letter L is a mnemonic for Load, but the command should not be
confused with the Load selection from the File menu, since that selection
only loads a source file without restarting the program.
====

<*> Examples

>L
>

The example above starts the current executable file, retaining any
breakpoints, watchpoints, tracepoints, and arguments.

>L 6
>

The example above restarts the current executable file, but with 6 as the new
program argument.

.end of chapter.